
\section{Units in Labels}
\label{sec:units}

\begingroup
\def\pgfplotsmanualcurlibrary{units}

{\noindent {\emph{by Nick Papior Andersen}}}

\begin{pgfplotslibrary}{units}
        \index{Tick Labels!Units (km, m, etc)}%
    A library which allows to use automatic typesetting of units in labels. The
    library utilizes different keys to typeset the final output in a consistent
    way. Calling one of the commands automatically sets the key
    `|use units=true|' so one does not have to worry about this.
\end{pgfplotslibrary}

\PGFPlots{} has the capability of supporting units. This provides quick
customization of the plot as well as the addition of units in labels.

Loading the library automatically enables the typesetting of units in labels.
Currently it only supports predefined SI units but a per-user customization is
also implemented such that it can be used in any way you like.

First the key which enables you to switch on/off the unit system.

\begin{pgfplotskey}{use units=\marg{boolean} (initially true)}
    This key simply enables \PGFPlots{} to use what is described next. This key
    will be set to true if you load the library. You can use this to
    temporarily determine whether the unit library should be used in plots.
\end{pgfplotskey}

\begin{pgfplotsxykey}{\x\ unit=\marg{unit} (initially empty)}
    These keys set the unit in their respective axis. In SI units you could for
    instance set the |x unit| in Newton as |x unit=N|.
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{\x\ unit prefix=\marg{prefix} (initially empty)}
    These keys set the prefix of the unit. If a value on the |y axis| is in
    kilo you would set the |y unit prefix=k|. Prefix will be typeset in front
    of the unit.

    This command will not intervene with the basis of the axis system. That is a
    prefix as just mentioned will not divide every |y axis| number by 1000. In
    order to do this, see key \meta{axis}| SI prefix|, see
    Section~\ref{sec:SI:prefix}.

    Notice that if the \meta{axis}| unit| isn't set the entire unit will not be
    typeset.


    \paragraph{Remarks:}

    Remember that all typesetting of labels occur within math mode (i.e.\@
    within \$ delimiters). Therefore one can use \textbackslash|frac| and
    other mathematics commands.
\end{pgfplotsxykey}

Often one just has to utilize the above mentioned keys. It is the basis of the
unit typesetting system provided by \PGFPlots{}.
%
% \usepgfplotslibrary{units}
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[use units,
    x unit=m,x unit prefix=k,
    y unit=N,y unit prefix=m,
    xlabel=Distance,ylabel=Force,
]
    \addplot coordinates {
        (1,2.3)
        (2,2.7)
        (3,2.1)
        (4,1.8)
        (5,1.5)
        (6,1.1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

Below is an example of what would be obtained according to the styles
%
\begin{codeexample}[code only]
% x label becomes ``Temperature [T]'', y label becomes ``Nothing''
\pgfplotsset{use units,x unit=T,xlabel=Temperature,ylabel=Nothing}
% x label becomes ``Temperature'', y label becomes ``Nothing''
\pgfplotsset{use units,x unit prefix=m,xlabel=Temperature,ylabel=Nothing}
\end{codeexample}
%
Notice the second example. Only setting the prefix will not activate the unit
typesetting. Therefore one should ensure to use the |x unit| key if the
typesetting of the labels should be done.

For typesetting the units one can also change the appearance. For instance one
might not like the square brackets which surround the unit. These can luckily
be changed using the below keys.

\begin{pgfplotskeylist}{unit marking pre=\marg{pre} (initially \textbackslash left[),unit marking post=\marg{post} (initially \textbackslash right]),unit markings=\mchoice{parenthesis,square brackets,slash space} (initially square brackets)}
    These keys set the surroundings of the unit. The initial yields
    $\left[\frac{1}{2}\right]$ such that you can typeset fractions in units. Be
    aware that you can only obtain large fractions if you use
    \textbackslash|dfrac|. These can easily be set using the option key
    |unit markings| where the options typesets as the following
    %
\begin{codeexample}[code only]
\pgfplotsset{x unit=T,unit markings=parenthesis} % x unit becomes `` \left(T\right)''
\pgfplotsset{x unit=T,unit markings=square brackets} % x unit becomes `` \left[T\right]''
\pgfplotsset{x unit=T,unit markings=slash space} % x unit becomes `` / T''
\end{codeexample}
    %
    Notice that all typesetting of units first inserts a space and then the
    |unit marking pre| code.

    Of course you can just manually set each of them with the
    |unit marking pre| and |unit marking post| keys. Just remember that they
    are typeset within a \$ delimiters.
\end{pgfplotskeylist}

One will typically typeset the unit with a specific font. To do so an option of
changing the typesetting command is supplied.

\begin{pgfplotscodetwokey}{unit code}%\textbackslash mathrm\{\})}
    This can be utilized to great extent. By default, units are typeset as
    |\mathrm{|\meta{unit prefix}\meta{unit}|}|. But if one for instance wishes
    to utilize the package |siunitx|, which has great capabilities in
    typesetting both units, numbers and angles, one can just set the key as
    %
\begin{codeexample}[code only]
\pgfplotsset{unit code/.code 2 args={\si{#1#2}}}
\end{codeexample}
    %
    which would yield the unit as |\si{|\meta{unit prefix}\meta{unit}|}|.

    The first argument is typeset as \meta{unit prefix} and the second argument
    is \meta{unit}.

    The most important thing is that the command needs exactly two arguments.
    So if you would like a command that typesets the prefix in bold face and
    the unit in normal roman font you should call
    %
\begin{codeexample}[code only]
\pgfplotsset{unit code/.code 2 args={\mathbf{#1}\mathrm{#2}}
\end{codeexample}
\end{pgfplotscodetwokey}


\subsection{Preset SI prefixes}
\label{sec:SI:prefix}
    \index{prefixes!unit}

To support the SI system a number of preset keys are defined. This should yield
a more intuitive way of supplying the prefix as well as add some more
functionality. For instance it provides an easy scaling mechanism.

\begin{pgfplotsxykeylist}{%
    \x\ SI prefix=\mchoice{
        yocto,\dots,milli,centi,deci,deca,hecto,kilo,\dots,yotta%
    } (initially none),
    change \x\ base=\mchoice{true,false} (initially false)%
}
    These keys sets the prefix of the unit. The allowed prefixes are:
    %
    \begin{center}
        \begin{tabular}{>{\ttfamily}c>{$}c<{$}}
                \toprule
            \textrm{Prefix} & $Power$ \\
                \midrule
            yocto           & -24     \\
            zepto           & -21     \\
            atto            & -18     \\
            femto           & -15     \\
            pico            & -12     \\
            nano            & -9      \\
            micro           & -6      \\
            milli           & -3      \\
            centi           & -2      \\
            deci            & -1      \\
                \bottomrule
        \end{tabular}
            \qquad\qquad
        \begin{tabular}{>{\ttfamily}cc}
                \toprule
            \textrm{ Prefix} & Power \\
                \midrule
            deca             & 1     \\
            hecto            & 2     \\
            kilo             & 3     \\
            mega             & 6     \\
            giga             & 9     \\
            tera             & 12    \\
            peta             & 15    \\
            exa              & 18    \\
            zetta            & 21    \\
            yotta            & 24    \\
                \bottomrule
        \end{tabular}
    \end{center}
    %
    As well as resetting the base of the axis if the key
    |change |\meta{axis}| base=true|. Just \textbf{remember} to set the
    |change |\meta{axis}| base| before using the \meta{axis}| SI prefix| key.

    See the utilization as in the example below.
    %
% \usepgfplotslibrary{units}
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    change x base,
    x SI prefix=kilo,x unit=m,
    y SI prefix=milli,y unit=N,
    xlabel=Distance,ylabel=Force,
]
    \addplot coordinates {
        (1000,1)
        (2000,1.1)
        (3000,1.2)
        (4000,1.3)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    Notice that the |x axis| has changed base without displaying the $\cdot
    10^{3}$. This is done by using the key |change x base|. Even though you
    have used the key |y SI prefix=milli| the base isn't changed on the
    |y axis|. Try adding |change y base| just after |change x base| and see the
    result!
\end{pgfplotsxykeylist}

The above keys are the easy implementation of the base change. Below is a
further customization of the base change. It makes it easy to implement a
prefix with a custom base change.

\begin{pgfplotskey}{axis base prefix=%
    {axis \marg{axis} base \marg{base} prefix \marg{prefix}} (initially empty)%
}
    One can utilize this key to customize further of the base and setting the
    prefix.
    %
\begin{codeexample}[code only]
\pgfplotsset{change x base,axis base prefix={axis x base -3 prefix k}}
\pgfplotsset{change x base,x SI prefix=kilo}
\end{codeexample}
    %
    The above two commands are thus equivalent. Remember that the base should
    operate in opposite of prefix!
\end{pgfplotskey}
\endgroup
